MS-DOS is a registered trademark of Microsoft Corporation
IBM, IBM-PC, IBM-XT, AT, are registered trademarks of International Business Machines, Inc. WILDCAT! is a trademark of Mustang Software. XMODEM is a public-domain file-transfer protocol developed by Ward Christensen.
JMODEM is released into the public domain. As with most public-domain protocols, you are advised that there is no implied warranty of any kind. The source-code is provided so that you may determine for yourself if this program may serve a useful purpose. It is written in Microsoft MASM Assembly-language using good standards of engineering practice. It does not use any strange or "undocumented" functions of the MS-DOS operating system.
PLEASE UPLOAD THIS FILE (The ARC file) to as many
BBS systems as you can so that it gets installed
all around the country.
Introduction:
JMODEM is a new file-transfer protocol developed to be used as an "external protocol" on BBS systems and personal computers using the IBM-PC/AT/XT structure and the MS-DOS operating system.
This file-transfer system features:
o 16-bit CRC for verification
o File size is exactly maintained
o Data compression.
o Rapid host/remote synchronization.
o Variable-length transmission blocks which,
if there are few errors, increase to 8192
data-bytes in length.
o Flow control (automatic)
o Hangup protection
o Aborted files are saved
o Files being overwritten are renamed to
".OLD", rather than deleted.
o COM1 / COM2 support.
o Interrupt on received characters allows data
to be received while the previous block is
being written to disk. This provides almost
continuous data transmission without long
waits between blocks.
JMODEM is not for everyone! It does not have any pretty screens to dazzle the user. It is designed to maximize the amount of data that can be transferred in a given time (and reduce telephone cost). It does this by sending very long blocks of data and encoding (compressing) the data wherever possible. Since long blocks of data are subject to many transmission errors, a 16 bit CRC is used to determine the data integrity. As many as ten retries are made if the data is not correctly received. If you have a noisy telephone circuit, you will find that JMODEM will abort more often than the XMODEM protocol which sends very short blocks. A future version that will be downward-compatible with the existing version is being developed that will do "heroic" retries and will even go down to a 16-byte block-lengths if that's what is necessary to get the data transferred.
Once synchronization between the remote computer and the host are established, JMODEM paints a status block on the screen that shows how the file transfer is going. The status screen shows the block being transmitted (or the last received), the length of the block, and the total bytes having been transmitted (or received). A special synch~ronization routine is used so that the first block is not thrown away as happens so often in XMODEM type routines. During the synchronization routine, where the host is waiting for the user to enter the proper file parameters (a 30 second wait). You can abort immediately by sending a control X (^X). After actual file transfer begins, ie. when you see the status window on the screen, no input from the keyboard is possible. You send a control BREAK to abort the transmission (or ^C). In this case, the program will abort after the block being sent/received is complete. This could take 15 or more seconds with long blocks so be patient.
In the event that carrier is lost (the user disconnected), the file-transfer program will also abort. This, too, could take as long as 15 seconds.
How it works:
The block size starts out at 512 bytes (or the actual bytes in the file -- whichever is less). To this is added a 6-byte overhead. If the block transfer occurred without any retries, the block length is increased by 512 bytes to 1024 bytes. As long as the transmission was successful without incurring any re-tries, the block-length increases to a maximum of 8192 bytes. There is still the same 6-byte overhead so the maximum block length will actually be 8198 bytes. Any time there are retries, the block length (on the next new string) is decreased by 512 bytes. The string-length is never reduced to less than 512 bytes due to errors. When the last bytes are read from the file, the block length may be as little as 7 bytes (one data byte, plus the 6 byte overhead). The file size as received will be exactly the file size as transmitted. XMODEM will "round-up" the file size to the next higher block. This means that MS-DOS's COMP (compare) will always fail when you attempt to check files that have been sent by XMODEM and many other protocols.
When the file is read, an attempt is made to compress the data using the well-known RLL process where multiple bytes are compressed into a 4-byte statement.
For instance a string that looks like this (hex):
A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0
Gets compressed into this:
BB 0F 00 A0
| | | |__________ Byte to repeat
| | |_____________ High byte of repeat length
| |________________ Low byte of repeat length
|___________________ Sentinel Byte
The sentinel-byte (BBH), when encountered in a data stream will get expanded to four bytes. Therefore, it is possible for the "compressed" data string to actually be longer than the original. If this occurs, the original string is sent rather than the longer encoded one. Since the kind of data sent can be different from block-to-block, it is necessary to send a control-byte along with the data so the receiver had determine how to operate on the data.
Two bytes are used for the string length and two bytes are used for the CRC. As is standard in memory, the high-byte looks "to people using DEBUG" swapped with the low byte. The data is transmitted exactly as the memory image.
The length (a word) begins the string so the receiver may know exactly how may bytes to receive.
The control byte is bit-mapped to 8 possibilities. The ones most important are:
NORMAL DATA
COMPRESSED DATA
END OF FILE
ABORT
This is now the receiver "knows" what to do with the data.
The CRC is generated using this polynomial:
X = X + X^(2(n-mod 7)....... Where n = t(n-1)
And t = string length
It has the advantage of simplicity in assembly-language programming and will detect errors with a probability of about one undetected error in 2^132 (which is a very large number). It does not correct errors so its not important to use some "standard" function to generate the CRC.
Usage:
This program uses parameters on the command line.
JMODEM S <filename.typ> ( Sends a file to COM1:)
JMODEM R <filename.typ> ( Receives a file from COM1:)
JMODEM S1 <filename.typ> ( Sends a file to COM1:)
JMODEM R1 <filename.typ> ( Receives a file from COM1:)
JMODEM S2 <filename.typ> ( Sends a file to COM2:)
JMODEM R2 <filename.typ> ( Receives a file from COM2:)
Support for COM3 and COM4 have been added on revision level V1.05 . Note that the standards for port locations are de-facto standards only and may not be the ports actually used in your computer. Please modify the communications port structures at the beginning of the assembly-language program to match your system parameters if they are different. The modifications should be done to the STRUCTURES, not to the EQUATES!
In a batch file, <filename.typ> may be a substitution character.
JMODEM S2 %1 ( Sends a file to COM2:)
JMODEM R2 %1 ( Receives a file from COM2:)
How to set up batch files to use this program:
If you are using PCPLUS (PROCOMM +), the batch files should be set up like this:
(JDOWN.BAT)
JMODEM R1 %1 ( Download from COM1:)
(JUP.BAT)
JMODEM S1 %1 ( Upload to COM1:)
If you are running a WILDCAT! bulletin board, the external protocol files should be set up like this:
(JUP.BAT)
CD D:\WILDCAT\PROTOCOL
IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
JMODEM R1 %3
IF ERRORLEVEL 1 GOTO END
COPY %3 %4
:END
DEL %3
(JDOWN.BAT)
CD D:\WILDCAT\PROTOCOL
IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
JMODEM S1 %3
IF ERRORLEVEL 1 GOTO BAD
GOTO END
:BAD
COPY ALL.OK TRANSFER.BAD
:END
JMODEM does not require any information about handshaking. It will look at the modem port and figure out for itself what to do.
In the event that the modem carrier is lost, JMODEM will abort. Since JMODEM only checks the modem port occasionally, it may take several seconds to abort when the carrier is lost. It is impossible for a user to get at the DOS level through JMODEM. Do NOT use the CTTY command in the external protocol batch files. JMODEM returns ERRORLEVEL 1 if there was any error in transmission or reception. It returns ERRORLEVEL 0 (no error) otherwise. It does not delete files that have been partially received although it properly closes them. The system operator can arrange the batch files to delete them if required.
When JMODEM attempts to create a file that already exists it can't ask the user if the old one should be deleted since the user is probably not in a terminal program at the time. Therefore, JMODEM renames the other file to <filename.OLD> and creates the new file.
